Rendering a Model

To render a model using a view, you call QuickDraw 3D functions that submit the various shape objects (for instance, geometric objects, groups of geometric objects, and styles) that you want to appear in the view. Because a model might be too complex to process in a single pass (and for other reasons as well), you should call the rendering routines in a rendering loop. A rendering loop begins with a call to the Q3View_StartRendering function and should end when a call to the Q3View_EndRendering function returns some value other than kQ3ViewStatusRetraverse . Within the body of the rendering loop, you should submit the shapes you want rendered. Listing 10 shows the general structure of a rendering loop.

Listing 10 A basic rendering loop

Q3View_StartRendering(myView);
do {
    /*Submit your shape objects here.*/
    Q3DisplayGroup_Submit(myGroup, myView);
} while (Q3View_EndRendering(myView) == kQ3ViewStatusRetraverse);


The Q3View_EndRendering function returns a view status value that indicates whether the renderer has finished processing the model. The available view status values are defined by these constants:

typedef enum {
    kQ3ViewStatusDone,
    kQ3ViewStatusRetraverse,
    kQ3ViewStatusError,
    kQ3ViewStatusCancelled
} TQ3ViewStatus;


Listing 11 illustrates how to render the model defined in Listing 4 , using the view created and configured in Listing 9 . The MyDraw function defined in Listing 11 retrieves the window information structure attached to a window and uses the information in it to render the model.

Listing 11 Rendering a model

void MyDraw (WindowPtr theWindow)
{
    WindowInfoHandle                myWinfo;
    TQ3Status                       myStat;
    TQ3DrawContextObject            myDrawContext;
    TQ3ViewStatus                   myViewStatus;
    
    if (theWindow == NULL)
        return;

    myWinfo = (WindowInfoHandle) GetWRefCon(theWindow);
    HLock((Handle) myWinfo);
    
    /*Start rendering.*/
    myStat = Q3View_StartRendering((**myWinfo).view);
    if (myStat == kQ3Failure)
        goto bail;

    do {
        myStat = Q3Shader_Submit((**myWinfo).illumination, (**myWinfo).view);
        if (myStat == kQ3Failure)
            goto bail;
        myStat = Q3Style_Submit((**myWinfo).interpolation, (**myWinfo).view);
        if (myStat == kQ3Failure)
            goto bail;
        myStat = Q3Style_Submit((**myWinfo).backfacing, (**myWinfo).view);
        if (myStat == kQ3Failure)
            goto bail;
        myStat = Q3Style_Submit((**myWinfo).fillstyle, (**myWinfo).view);
        if (myStat == kQ3Failure)
            goto bail;
        myStat = Q3DisplayGroup_Submit((**myWinfo).model, (**myWinfo).view);
        if (myStat == kQ3Failure)
            goto bail;
        myViewStatus = Q3View_EndRendering((**myWinfo).view);
    } while (myViewStatus == kQ3ViewStatusRetraverse);
    HUnlock((Handle) myWinfo);
    return;

bail:
    HUnlock((Handle) myWinfo);
    SysBeep(50);
}


The rendering loop allows your application to work with any current and future renderers that require multiple passes through a model's data in order to provide features such as transparency and constructive solid geometry.

For complete information about rendering loops and other kinds of submitting loops, see the chapter "View Objects" in this book.

---

© 1997 Apple Computer, Inc.

Previous | QD3D Book | Overview | Chapter Contents | Next |